{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "597OjogAI3fy"
      },
      "source": [
        "##### Copyright 2019 The TensorFlow Authors."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "cellView": "form",
        "colab": {},
        "colab_type": "code",
        "id": "5bSCD8SyJC2g"
      },
      "outputs": [],
      "source": [
        "#@title Licensed under the Apache License, Version 2.0 (the \"License\");\n",
        "# you may not use this file except in compliance with the License.\n",
        "# You may obtain a copy of the License at\n",
        "#\n",
        "# https://www.apache.org/licenses/LICENSE-2.0\n",
        "#\n",
        "# Unless required by applicable law or agreed to in writing, software\n",
        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
        "# See the License for the specific language governing permissions and\n",
        "# limitations under the License."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "E_ceEiH7g0MY"
      },
      "source": [
        "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
        "  <td>\n",
        "    <a target=\"_blank\" href=\"https://www.tensorflow.org/guide/keras/custom_callback\"><img src=\"https://www.tensorflow.org/images/tf_logo_32px.png\" />View on TensorFlow.org</a>\n",
        "  </td>\n",
        "  <td>\n",
        "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/guide/keras/custom_callback.ipynb\"><img src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
        "  </td>\n",
        "  <td>\n",
        "    <a target=\"_blank\" href=\"https://github.com/tensorflow/docs/blob/master/site/en/guide/keras/custom_callback.ipynb\"><img src=\"https://www.tensorflow.org/images/GitHub-Mark-32px.png\" />View source on GitHub</a>\n",
        "  </td>\n",
        "  <td>\n",
        "    <a href=\"https://storage.googleapis.com/tensorflow_docs/docs/site/en/guide/keras/custom_callback.ipynb\"><img src=\"https://www.tensorflow.org/images/download_logo_32px.png\" />Download notebook</a>\n",
        "  </td>\n",
        "</table>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "1OykC-6lI4gv"
      },
      "source": [
        "# Keras custom callbacks\n",
        "A custom callback is a powerful tool to customize the behavior of a Keras model during training, evaluation, or inference, including reading/changing the Keras model. Examples include `tf.keras.callbacks.TensorBoard` where the training progress and results can be exported and visualized with TensorBoard, or `tf.keras.callbacks.ModelCheckpoint` where the model is automatically saved during training, and more. In this guide, you will learn what Keras callback is, when it will be called, what it can do, and how you can build your own. Towards the end of this guide, there will be demos of creating a couple of simple callback applications to get you started on your custom callback."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "d5zZ8rZD69VW"
      },
      "source": [
        "## Setup"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "7BazS4qD6-2n"
      },
      "outputs": [],
      "source": [
        "import tensorflow as tf"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "0c_TYhQOUe1j"
      },
      "source": [
        "## Introduction to Keras callbacks\n",
        "In Keras, `Callback` is a python class meant to be subclassed to provide specific functionality, with a set of methods called at various stages of training (including batch/epoch start and ends), testing, and predicting. Callbacks are useful to get a view on internal states and statistics of the model during training. You can pass a list of callbacks (as the keyword argument `callbacks`) to any of `tf.keras.Model.fit()`, `tf.keras.Model.evaluate()`, and `tf.keras.Model.predict()` methods. The methods of the callbacks will then be called at different stages of training/evaluating/inference.\n",
        "\n",
        "To get started, let's import tensorflow and define a simple Sequential Keras model:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "Ct0VCSI2dt3a"
      },
      "outputs": [],
      "source": [
        "# Define the Keras model to add callbacks to\n",
        "def get_model():\n",
        "  model = tf.keras.Sequential()\n",
        "  model.add(tf.keras.layers.Dense(1, activation = 'linear', input_dim = 784))\n",
        "  model.compile(optimizer=tf.keras.optimizers.RMSprop(lr=0.1), loss='mean_squared_error', metrics=['mae'])\n",
        "  return model"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "ySzdG1IqNgah"
      },
      "source": [
        "Then, load the MNIST data for training and testing from Keras datasets API:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "fwo9LMKGNPWr"
      },
      "outputs": [],
      "source": [
        "# Load example MNIST data and pre-process it\n",
        "(x_train, y_train), (x_test, y_test) = tf.keras.datasets.mnist.load_data()\n",
        "x_train = x_train.reshape(60000, 784).astype('float32') / 255\n",
        "x_test = x_test.reshape(10000, 784).astype('float32') / 255"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "kHVK7kceNqH2"
      },
      "source": [
        "Now, define a simple custom callback to track the start and end of every batch of data. During those calls, it prints the index of the current batch."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "-dfuGTMINKRR"
      },
      "outputs": [],
      "source": [
        "import datetime\n",
        "\n",
        "class MyCustomCallback(tf.keras.callbacks.Callback):\n",
        "\n",
        "  def on_train_batch_begin(self, batch, logs=None):\n",
        "    print('Training: batch {} begins at {}'.format(batch, datetime.datetime.now().time()))\n",
        "\n",
        "  def on_train_batch_end(self, batch, logs=None):\n",
        "    print('Training: batch {} ends at {}'.format(batch, datetime.datetime.now().time()))\n",
        "\n",
        "  def on_test_batch_begin(self, batch, logs=None):\n",
        "    print('Evaluating: batch {} begins at {}'.format(batch, datetime.datetime.now().time()))\n",
        "\n",
        "  def on_test_batch_end(self, batch, logs=None):\n",
        "    print('Evaluating: batch {} ends at {}'.format(batch, datetime.datetime.now().time()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "Z4FTUUIBN3WG"
      },
      "source": [
        "Providing a callback to model methods such as `tf.keras.Model.fit()` ensures the methods are called at those stages:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "NJV6Tj3sNGzg"
      },
      "outputs": [],
      "source": [
        "model = get_model()\n",
        "_ = model.fit(x_train, y_train,\n",
        "          batch_size=64,\n",
        "          epochs=1,\n",
        "          steps_per_epoch=5,\n",
        "          verbose=0,\n",
        "          callbacks=[MyCustomCallback()])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "fIy5JKMlZNmh"
      },
      "source": [
        "## Model methods that take callbacks\n",
        "Users can supply a list of callbacks to the following `tf.keras.Model` methods:\n",
        "#### [`fit()`](https://www.tensorflow.org/api_docs/python/tf/keras/Model#fit), [`fit_generator()`](https://www.tensorflow.org/api_docs/python/tf/keras/Model#fit_generator)\n",
        "Trains the model for a fixed number of epochs (iterations over a dataset, or data yielded batch-by-batch by a Python generator).\n",
        "#### [`evaluate()`](https://www.tensorflow.org/api_docs/python/tf/keras/Model#evaluate), [`evaluate_generator()`](https://www.tensorflow.org/api_docs/python/tf/keras/Model#evaluate_generator)\n",
        "Evaluates the model for given data or data generator. Outputs the loss and metric values from the evaluation.\n",
        "#### [`predict()`](https://www.tensorflow.org/api_docs/python/tf/keras/Model#predict), [`predict_generator()`](https://www.tensorflow.org/api_docs/python/tf/keras/Model#predict_generator)\n",
        "Generates output predictions for the input data or data generator.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "J00bXBbqdnJe"
      },
      "outputs": [],
      "source": [
        "_ = model.evaluate(x_test, y_test, batch_size=128, verbose=0, steps=5,\n",
        "          callbacks=[MyCustomCallback()])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "13n44LVkYQsV"
      },
      "source": [
        "## An overview of callback methods\n",
        "\n",
        "\n",
        "### Common methods for training/testing/predicting\n",
        "For training, testing, and predicting, following methods are provided to be overridden.\n",
        "#### `on_(train|test|predict)_begin(self, logs=None)`\n",
        "Called at the beginning of `fit`/`evaluate`/`predict`.\n",
        "#### `on_(train|test|predict)_end(self, logs=None)`\n",
        "Called at the end of `fit`/`evaluate`/`predict`.\n",
        "#### `on_(train|test|predict)_batch_begin(self, batch, logs=None)`\n",
        "Called right before processing a batch during training/testing/predicting. Within this method, `logs` is a dict with `batch` and `size` available keys, representing the current batch number and the size of the batch.\n",
        "#### `on_(train|test|predict)_batch_end(self, batch, logs=None)`\n",
        "Called at the end of training/testing/predicting a batch. Within this method, `logs` is a dict containing the stateful metrics result.\n",
        "\n",
        "### Training specific methods\n",
        "In addition, for training, following are provided.\n",
        "#### on_epoch_begin(self, epoch, logs=None)\n",
        "Called at the beginning of an epoch during training.\n",
        "#### on_epoch_end(self, epoch, logs=None)\n",
        "Called at the end of an epoch during training.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "SWf3mXYoceCz"
      },
      "source": [
        "### Usage of `logs` dict\n",
        "The `logs` dict contains the loss value, and all the metrics at the end of a batch or epoch. Example includes the loss and mean absolute error."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "u4wIdcF9BjJH"
      },
      "outputs": [],
      "source": [
        "class LossAndErrorPrintingCallback(tf.keras.callbacks.Callback):\n",
        "\n",
        "  def on_train_batch_end(self, batch, logs=None):\n",
        "    print('For batch {}, loss is {:7.2f}.'.format(batch, logs['loss']))\n",
        "\n",
        "  def on_test_batch_end(self, batch, logs=None):\n",
        "    print('For batch {}, loss is {:7.2f}.'.format(batch, logs['loss']))\n",
        "\n",
        "  def on_epoch_end(self, epoch, logs=None):\n",
        "    print('The average loss for epoch {} is {:7.2f} and mean absolute error is {:7.2f}.'.format(epoch, logs['loss'], logs['mae']))\n",
        "\n",
        "model = get_model()\n",
        "_ = model.fit(x_train, y_train,\n",
        "          batch_size=64,\n",
        "          steps_per_epoch=5,\n",
        "          epochs=3,\n",
        "          verbose=0,\n",
        "          callbacks=[LossAndErrorPrintingCallback()])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "LbXqvC8FHqeu"
      },
      "source": [
        "Similarly, one can provide callbacks in `evaluate()` calls."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "jzTKYPQHwcxF"
      },
      "outputs": [],
      "source": [
        "_ = model.evaluate(x_test, y_test, batch_size=128, verbose=0, steps=20,\n",
        "          callbacks=[LossAndErrorPrintingCallback()])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "HnSljqtsXKfb"
      },
      "source": [
        "## Examples of Keras callback applications\n",
        "The following section will guide you through creating simple Callback applications."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "kptNF0--Lznv"
      },
      "source": [
        "### Early stopping at minimum loss\n",
        "First example showcases the creation of a `Callback` that stops the Keras training when the minimum of loss has been reached by mutating the attribute `model.stop_training` (boolean). Optionally, the user can provide an argument `patience` to specify how many epochs the training should wait before it eventually stops.\n",
        "\n",
        "`tf.keras.callbacks.EarlyStopping` provides a more complete and general implementation."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "BM31gfAV4mks"
      },
      "outputs": [],
      "source": [
        "import numpy as np\n",
        "\n",
        "class EarlyStoppingAtMinLoss(tf.keras.callbacks.Callback):\n",
        "  \"\"\"Stop training when the loss is at its min, i.e. the loss stops decreasing.\n",
        "\n",
        "  Arguments:\n",
        "      patience: Number of epochs to wait after min has been hit. After this\n",
        "      number of no improvement, training stops.\n",
        "  \"\"\"\n",
        "\n",
        "  def __init__(self, patience=0):\n",
        "    super(EarlyStoppingAtMinLoss, self).__init__()\n",
        "\n",
        "    self.patience = patience\n",
        "\n",
        "    # best_weights to store the weights at which the minimum loss occurs.\n",
        "    self.best_weights = None\n",
        "\n",
        "  def on_train_begin(self, logs=None):\n",
        "    # The number of epoch it has waited when loss is no longer minimum.\n",
        "    self.wait = 0\n",
        "    # The epoch the training stops at.\n",
        "    self.stopped_epoch = 0\n",
        "    # Initialize the best as infinity.\n",
        "    self.best = np.Inf\n",
        "\n",
        "  def on_epoch_end(self, epoch, logs=None):\n",
        "    current = logs.get('loss')\n",
        "    if np.less(current, self.best):\n",
        "      self.best = current\n",
        "      self.wait = 0\n",
        "      # Record the best weights if current results is better (less).\n",
        "      self.best_weights = self.model.get_weights()\n",
        "    else:\n",
        "      self.wait += 1\n",
        "      if self.wait >= self.patience:\n",
        "        self.stopped_epoch = epoch\n",
        "        self.model.stop_training = True\n",
        "        print('Restoring model weights from the end of the best epoch.')\n",
        "        self.model.set_weights(self.best_weights)\n",
        "\n",
        "  def on_train_end(self, logs=None):\n",
        "    if self.stopped_epoch > 0:\n",
        "      print('Epoch %05d: early stopping' % (self.stopped_epoch + 1))"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "xS4fa-7PFzzc"
      },
      "outputs": [],
      "source": [
        "model = get_model()\n",
        "_ = model.fit(x_train, y_train,\n",
        "          batch_size=64,\n",
        "          steps_per_epoch=5,\n",
        "          epochs=30,\n",
        "          verbose=0,\n",
        "          callbacks=[LossAndErrorPrintingCallback(), EarlyStoppingAtMinLoss()])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "SpVDjs_Dkkdh"
      },
      "source": [
        "### Learning rate scheduling\n",
        "\n",
        "One thing that is commonly done in model training is changing the learning rate as more epochs have passed. Keras backend exposes `get_value` API which can be used to set the variables. In this example, we're showing how a custom Callback can be used to dynamically change the learning rate.\n",
        "\n",
        "Note: This is just an example implementation. See `callbacks.LearningRateScheduler` and `keras.optimizers.schedules` for more general implementations."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "PGowEUC8klSz"
      },
      "outputs": [],
      "source": [
        "class LearningRateScheduler(tf.keras.callbacks.Callback):\n",
        "  \"\"\"Learning rate scheduler which sets the learning rate according to schedule.\n",
        "\n",
        "  Arguments:\n",
        "      schedule: a function that takes an epoch index\n",
        "          (integer, indexed from 0) and current learning rate\n",
        "          as inputs and returns a new learning rate as output (float).\n",
        "  \"\"\"\n",
        "\n",
        "  def __init__(self, schedule):\n",
        "    super(LearningRateScheduler, self).__init__()\n",
        "    self.schedule = schedule\n",
        "\n",
        "  def on_epoch_begin(self, epoch, logs=None):\n",
        "    if not hasattr(self.model.optimizer, 'lr'):\n",
        "      raise ValueError('Optimizer must have a \"lr\" attribute.')\n",
        "    # Get the current learning rate from model's optimizer.\n",
        "    lr = float(tf.keras.backend.get_value(self.model.optimizer.lr))\n",
        "    # Call schedule function to get the scheduled learning rate.\n",
        "    scheduled_lr = self.schedule(epoch, lr)\n",
        "    # Set the value back to the optimizer before this epoch starts\n",
        "    tf.keras.backend.set_value(self.model.optimizer.lr, scheduled_lr)\n",
        "    print('\\nEpoch %05d: Learning rate is %6.4f.' % (epoch, scheduled_lr))"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 0,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "1jL3pI5Ep5F8"
      },
      "outputs": [],
      "source": [
        "LR_SCHEDULE = [\n",
        "    # (epoch to start, learning rate) tuples\n",
        "    (3, 0.05), (6, 0.01), (9, 0.005), (12, 0.001)\n",
        "]\n",
        "\n",
        "def lr_schedule(epoch, lr):\n",
        "  \"\"\"Helper function to retrieve the scheduled learning rate based on epoch.\"\"\"\n",
        "  if epoch < LR_SCHEDULE[0][0] or epoch > LR_SCHEDULE[-1][0]:\n",
        "    return lr\n",
        "  for i in range(len(LR_SCHEDULE)):\n",
        "    if epoch == LR_SCHEDULE[i][0]:\n",
        "      return LR_SCHEDULE[i][1]\n",
        "  return lr\n",
        "\n",
        "model = get_model()\n",
        "_ = model.fit(x_train, y_train,\n",
        "          batch_size=64,\n",
        "          steps_per_epoch=5,\n",
        "          epochs=15,\n",
        "          verbose=0,\n",
        "          callbacks=[LossAndErrorPrintingCallback(), LearningRateScheduler(lr_schedule)])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "9xMkm699JzK8"
      },
      "source": [
        "### Standard Keras callbacks\n",
        "Be sure to check out the existing Keras callbacks by [visiting the API doc](https://www.tensorflow.org/api_docs/python/tf/keras/callbacks). Applications include logging to CSV, saving the model, visualizing on TensorBoard and a lot more."
      ]
    }
  ],
  "metadata": {
    "colab": {
      "collapsed_sections": [
        "9xMkm699JzK8"
      ],
      "name": "custom_callback.ipynb",
      "private_outputs": true,
      "provenance": [],
      "toc_visible": true,
      "version": "0.3.2"
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}
